v0.21.4: Released: StructArmed 0.21.4

Compare Source

What's Changed

• fix: Match language constructs case-insensitively in usesLanguageConstruct() by @​samsonasik in #​543

Full Changelog: boundwize/structarmed@0.21.3...0.21.4

v0.21.3: Released: StructArmed 0.21.3

Compare Source

What's Changed

• [dx] Mention promoted members in ApiMayNotExposeInternalRule violation message by @​samsonasik in #​542

Full Changelog: boundwize/structarmed@0.21.2...0.21.3

v0.21.2: Released: StructArmed 0.21.2

Compare Source

What's Changed

• [dx] Make isPromoted = true flag on Param as well by @​samsonasik in #​541

Full Changelog: boundwize/structarmed@0.21.1...0.21.2

v0.21.1: Released: StructArmed 0.21.1

Compare Source

What's Changed

• [dx] Add isPromoted to ClassSignature to tell promoted properties from declared ones by @​samsonasik in #​540

Full Changelog: boundwize/structarmed@0.21.0...0.21.1

v0.21.0: Released: StructArmed 0.21.0

Compare Source

StructArmed 0.21.0 introduces a new Enum preset, stronger API stability checks, signature type analysis for custom rules, and improved enum formatting support.

This release introduces:

• the new Preset::ENUM() for validating string-backed enum case values;
• ApiMayNotExposeInternalRule for preventing public APIs from exposing internal types;
• ClassSignature and SignatureTypesAwareRuleInterface for analyzing member signature types;
• the new fixable EnumCaseMustBeOnOwnLineRule in the PER preset;
• improved backed enum value resolution and analysis cache support.

New Enum Preset

StructArmed introduces a new preset for validating string-backed enum case values:

Preset::ENUM()

The preset includes two new rules:

• EnumCaseValueMustNotBeEmptyRule — prevents empty string-backed enum values.
• EnumCaseValueMustNotHaveSurroundingWhitespaceRule — prevents leading or trailing whitespace in string-backed enum values.

For example:

enum Status: string
{
    case Pending = '';
    case Active = ' active ';
    case Completed = 'completed';
}

The first two cases produce violations, while Completed is valid.

The rules check statically resolved string-backed values. Pure enums and integer-backed enums are unaffected.

These rules do not support --fix, as changing backing values could break existing APIs or persisted data.

Enable the preset with:

use Boundwize\StructArmed\Preset\Preset;

// In your architecture configuration:
->withPreset(Preset::ENUM())

Or initialize a new configuration:

vendor/bin/structarmed init --preset=enum

API Stability Improvements

The Stability preset now includes ApiMayNotExposeInternalRule, preventing @api declarations from exposing @internal types through public or protected signatures.

For example:

/** @internal */
class InternalService
{
}

/** @api */
class PublicService
{
    public function getService(): InternalService
    {
        return new InternalService();
    }
}

The rule reports an architecture violation because the public method exposes an internal implementation.

The rule checks:

• public and protected method parameter types;
• public and protected method return types;
• public and protected property types;
• constructor-promoted parameters that expose internal types.

Private implementation details remain unrestricted, except when exposed through a public or protected constructor parameter.

Only types within the scanned project are checked, since external declarations may not have available PHPDoc information.

New Signature Type Analysis

StructArmed introduces ClassSignature and SignatureTypesAwareRuleInterface for analyzing types referenced in class-like member signatures.

Each ClassSignature provides:

• type — fully qualified referenced type;
• name — originating property, parameter, or method;
• kind — property, parameter, or method;
• visibility — public, protected, or private;
• line — source line.

Custom rules can implement SignatureTypesAwareRuleInterface to access signature information through $classNode->signatures.

Custom Rule Example

For example, prevent public repository methods from returning Doctrine's QueryBuilder:

<?php

declare(strict_types=1);

namespace App\Architecture\Rules;

use Boundwize\StructArmed\Analyser\ClassNode;
use Boundwize\StructArmed\Analyser\ClassSignature;
use Boundwize\StructArmed\Rule\RuleViolation;
use Boundwize\StructArmed\Rule\SignatureTypesAwareRuleInterface;
use Doctrine\ORM\QueryBuilder;

final readonly class MayNotReturnQueryBuilderRule implements SignatureTypesAwareRuleInterface
{
    public function appliesTo(ClassNode $classNode): bool
    {
        return $classNode->nameEndsWith('Repository');
    }

    public function evaluate(ClassNode $classNode): ?RuleViolation
    {
        foreach ($classNode->signatures as $signature) {
            if (
                $signature->kind !== ClassSignature::METHOD
                || $signature->visibility !== 'public'
                || $signature->type !== QueryBuilder::class
            ) {
                continue;
            }

            return new RuleViolation(
                message: 'Public repository methods must not return QueryBuilder',
                file: $classNode->file,
                line: $signature->line,
                className: $classNode->className,
                layer: $classNode->layer,
            );
        }

        return null;
    }
}

With this rule, the following method produces a violation:

final class UserRepository
{
    public function createQuery(): QueryBuilder
    {
        // ...
    }
}

This allows repositories to use QueryBuilder internally without exposing it through their public APIs.

Signature collection is enabled only when an active rule implements SignatureTypesAwareRuleInterface, avoiding unnecessary analysis overhead and cache storage.

The collector supports nullable, union, intersection, and DNF types, including constructor-promoted properties.

PER Coding Style Improvements

The PER preset now includes EnumCaseMustBeOnOwnLineRule, requiring each enum case to be declared on its own line.

For example:

enum Status
{
    case Pending; case Active;
}

The rule supports automatic fixing:

vendor/bin/structarmed analyse --fix

Result:

enum Status
{
    case Pending;
    case Active;
}

The fixer preserves associated comments when moving enum cases, including comments on shared lines.

Bug Fixes and Internal Improvements

• Improve backed enum value resolution for local constants, including forward references.
• Add EnumCaseNode::sharesLine for detecting enum cases that share a line with another member or enum brace.
• Improve comment preservation when automatically formatting enum cases.
• Extend analysis caching to support optional signature collection.
• Update documentation and test coverage.

What's Changed

• Add API signature exposure analysis and ClassSignature support in #​524 and #​526.
• Improve backed enum value resolution in #​529.
• Add fixable enum case formatting to the PER preset in #​530.
• Introduce the new Enum preset and validation rules in #​536 and #​537.
• Preserve comments when moving enum cases onto separate lines in #​538.
• Prepare the 0.21.0 release in #​525.

Full Changelog: boundwize/structarmed@0.20.5...0.21.0